
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>10.7. Asymmetric signature &#8212; PSA Crypto API 1.1.0 documentation</title>
    <link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
    <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../../',
        VERSION:     '1.1.0',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false,
        SOURCELINK_SUFFIX: '.txt'
      };
    </script>
    <script type="text/javascript" src="../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../_static/doctools.js"></script>
    <link rel="author" title="About these documents" href="../../about.html" />
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="10.8. Asymmetric encryption" href="pke.html" />
    <link rel="prev" title="10.6. Key derivation" href="kdf.html" />
   
  <link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
  
  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />

  </head>
  <body>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="asymmetric-signature">
<span id="sign"></span><h1>10.7. Asymmetric signature</h1>
<p>There are two pairs of single-part functions for asymmetric signature:</p>
<ul>
<li><p class="first">The signature and verification functions <a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_message()</span></code></a> and <a class="reference internal" href="#c.psa_verify_message" title="psa_verify_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_message()</span></code></a> take a message as one of their inputs and perform a hash-and-sign algorithm.</p>
</li>
<li><p class="first">The functions <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a> and <a class="reference internal" href="#c.psa_verify_hash" title="psa_verify_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_hash()</span></code></a> take a message hash as one of their inputs. This is useful for signing pre-computed hashes, or for implementing hash-and-sign using a <a class="reference internal" href="hashes.html#hash-mp"><span class="std std-ref">multi-part hash operation</span></a> before signing the resulting hash. To determine which hash algorithm to use, call the macro <a class="reference internal" href="algorithms.html#c.PSA_ALG_GET_HASH" title="PSA_ALG_GET_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_GET_HASH()</span></code></a> on the corresponding signature algorithm.</p>
<p>Some hash-and-sign algorithms add padding to the message hash before completing the signing operation. The format of the padding that is used depends on the algorithm used to construct the signature.</p>
</li>
</ul>
<div class="section" id="asymmetric-signature-algorithms">
<span id="sign-algorithms"></span><h2>10.7.1. Asymmetric signature algorithms</h2>
<div class="section" id="PSA_ALG_RSA_PKCS1V15_SIGN">
<span id="c.PSA_ALG_RSA_PKCS1V15_SIGN"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_RSA_PKCS1V15_SIGN</span></code> (macro)</h3>
<p>The RSA PKCS#1 v1.5 message signature scheme, with hashing.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_RSA_PKCS1V15_SIGN" title="PSA_ALG_RSA_PKCS1V15_SIGN">PSA_ALG_RSA_PKCS1V15_SIGN</a>(hash_alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
<dd>A hash algorithm: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true. This includes <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a> when specifying the algorithm in a key policy.</dd>
</dl>
<p class="rubric">Returns</p>
<p>The corresponding RSA PKCS#1 v1.5 signature algorithm.</p>
<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
<p class="rubric">Description</p>
<p>This algorithm can be used with both the message and hash signature functions.</p>
<p>This signature scheme is defined by <span><em>PKCS #1: RSA Cryptography Specifications Version 2.2</em> <a class="reference internal" href="../../about.html#citation-rfc8017"><span class="cite">[RFC8017]</span></a></span> <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html#section-8.2">§8.2</a> under the name RSASSA-PKCS1-v1_5.</p>
<p>When used with <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a> or <a class="reference internal" href="#c.psa_verify_hash" title="psa_verify_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_hash()</span></code></a>, the provided <code class="docutils literal"><span class="pre">hash</span></code> parameter is used as <em>H</em> from step 2 onwards in the message encoding algorithm <code class="docutils literal"><span class="pre">EMSA-PKCS1-V1_5-ENCODE()</span></code> in <a class="reference internal" href="../../about.html#citation-rfc8017"><span class="cite">[RFC8017]</span></a> <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html#section-9.2">§9.2</a>. <em>H</em> is usually the message digest, using the <code class="docutils literal"><span class="pre">hash_alg</span></code> hash algorithm.</p>
<p class="rubric">Compatible key types</p>
<div class="line-block">
<div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_RSA_KEY_PAIR" title="PSA_KEY_TYPE_RSA_KEY_PAIR"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_RSA_KEY_PAIR</span></code></a></div>
<div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_RSA_PUBLIC_KEY" title="PSA_KEY_TYPE_RSA_PUBLIC_KEY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_RSA_PUBLIC_KEY</span></code></a> (signature verification only)</div>
</div>
</div>
<div class="section" id="PSA_ALG_RSA_PKCS1V15_SIGN_RAW">
<span id="c.PSA_ALG_RSA_PKCS1V15_SIGN_RAW"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_RSA_PKCS1V15_SIGN_RAW</span></code> (macro)</h3>
<p>The raw RSA PKCS#1 v1.5 signature algorithm, without hashing.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_RSA_PKCS1V15_SIGN_RAW" title="PSA_ALG_RSA_PKCS1V15_SIGN_RAW">PSA_ALG_RSA_PKCS1V15_SIGN_RAW</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>) 0x06000200)
</pre>
<p>This algorithm can be only used with the <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a> and <a class="reference internal" href="#c.psa_verify_hash" title="psa_verify_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_hash()</span></code></a> functions.</p>
<p>This signature scheme is defined by <span><em>PKCS #1: RSA Cryptography Specifications Version 2.2</em> <a class="reference internal" href="../../about.html#citation-rfc8017"><span class="cite">[RFC8017]</span></a></span> <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html#section-8.2">§8.2</a> under the name RSASSA-PKCS1-v1_5.</p>
<p>The <code class="docutils literal"><span class="pre">hash</span></code> parameter to <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a> or <a class="reference internal" href="#c.psa_verify_hash" title="psa_verify_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_hash()</span></code></a> is used as <em>T</em> from step 3 onwards in the message encoding algorithm <code class="docutils literal"><span class="pre">EMSA-PKCS1-V1_5-ENCODE()</span></code> in <a class="reference internal" href="../../about.html#citation-rfc8017"><span class="cite">[RFC8017]</span></a> <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html#section-9.2">§9.2</a>. <em>T</em> is the DER encoding of the <em>DigestInfo</em> structure normally produced by step 2 in the message encoding algorithm.</p>
<p>The wildcard key policy <a class="reference internal" href="#c.PSA_ALG_RSA_PKCS1V15_SIGN" title="PSA_ALG_RSA_PKCS1V15_SIGN"><code class="docutils literal"><span class="pre">PSA_ALG_RSA_PKCS1V15_SIGN</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a><code class="docutils literal"><span class="pre">)</span></code> also permits a key to be used with the <a class="reference internal" href="#c.PSA_ALG_RSA_PKCS1V15_SIGN_RAW" title="PSA_ALG_RSA_PKCS1V15_SIGN_RAW"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_RSA_PKCS1V15_SIGN_RAW</span></code></a> signature algorithm.</p>
<p class="rubric">Compatible key types</p>
<div class="line-block">
<div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_RSA_KEY_PAIR" title="PSA_KEY_TYPE_RSA_KEY_PAIR"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_RSA_KEY_PAIR</span></code></a></div>
<div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_RSA_PUBLIC_KEY" title="PSA_KEY_TYPE_RSA_PUBLIC_KEY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_RSA_PUBLIC_KEY</span></code></a> (signature verification only)</div>
</div>
</div>
<div class="section" id="PSA_ALG_RSA_PSS">
<span id="c.PSA_ALG_RSA_PSS"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_RSA_PSS</span></code> (macro)</h3>
<p>The RSA PSS message signature scheme, with hashing.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_RSA_PSS" title="PSA_ALG_RSA_PSS">PSA_ALG_RSA_PSS</a>(hash_alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
<dd>A hash algorithm: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true. This includes <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a> when specifying the algorithm in a key policy.</dd>
</dl>
<p class="rubric">Returns</p>
<p>The corresponding RSA PSS signature algorithm.</p>
<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
<p class="rubric">Description</p>
<p>This algorithm can be used with both the message and hash signature functions.</p>
<p>This algorithm is randomized: each invocation returns a different, equally valid signature.</p>
<p>This is the signature scheme defined by <a class="reference internal" href="../../about.html#citation-rfc8017"><span class="cite">[RFC8017]</span></a> <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html#section-8.1">§8.1</a> under the name RSASSA-PSS, with the following options:</p>
<ul class="simple">
<li>The mask generation function is <em>MGF1</em> defined by <a class="reference internal" href="../../about.html#citation-rfc8017"><span class="cite">[RFC8017]</span></a> <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html#appendix-B">Appendix B</a>.</li>
<li>When creating a signature, the salt length is equal to the length of the hash, or the largest possible salt length for the algorithm and key size if that is smaller than the hash length.</li>
<li>When verifying a signature, the salt length must be equal to the length of the hash, or the largest possible salt length for the algorithm and key size if that is smaller than the hash length.</li>
<li>The specified hash algorithm is used to hash the input message, to create the salted hash, and for the mask generation.</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <a class="reference internal" href="#c.PSA_ALG_RSA_PSS_ANY_SALT" title="PSA_ALG_RSA_PSS_ANY_SALT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_RSA_PSS_ANY_SALT()</span></code></a> algorithm is equivalent to <a class="reference internal" href="#c.PSA_ALG_RSA_PSS" title="PSA_ALG_RSA_PSS"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_RSA_PSS()</span></code></a> when creating a signature, but permits any salt length when verifying a signature.</p>
</div>
<p class="rubric">Compatible key types</p>
<div class="line-block">
<div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_RSA_KEY_PAIR" title="PSA_KEY_TYPE_RSA_KEY_PAIR"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_RSA_KEY_PAIR</span></code></a></div>
<div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_RSA_PUBLIC_KEY" title="PSA_KEY_TYPE_RSA_PUBLIC_KEY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_RSA_PUBLIC_KEY</span></code></a> (signature verification only)</div>
</div>
</div>
<div class="section" id="PSA_ALG_RSA_PSS_ANY_SALT">
<span id="c.PSA_ALG_RSA_PSS_ANY_SALT"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_RSA_PSS_ANY_SALT</span></code> (macro)</h3>
<p>The RSA PSS message signature scheme, with hashing.
This variant permits any salt length for signature verification.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_RSA_PSS_ANY_SALT" title="PSA_ALG_RSA_PSS_ANY_SALT">PSA_ALG_RSA_PSS_ANY_SALT</a>(hash_alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
<dd>A hash algorithm: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true. This includes <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a> when specifying the algorithm in a key policy.</dd>
</dl>
<p class="rubric">Returns</p>
<p>The corresponding RSA PSS signature algorithm.</p>
<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
<p class="rubric">Description</p>
<p>This algorithm can be used with both the message and hash signature functions.</p>
<p>This algorithm is randomized: each invocation returns a different, equally valid signature.</p>
<p>This is the signature scheme defined by <a class="reference internal" href="../../about.html#citation-rfc8017"><span class="cite">[RFC8017]</span></a> <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html#section-8.1">§8.1</a> under the name RSASSA-PSS, with the following options:</p>
<ul class="simple">
<li>The mask generation function is <em>MGF1</em> defined by <a class="reference internal" href="../../about.html#citation-rfc8017"><span class="cite">[RFC8017]</span></a> <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html#appendix-B">Appendix B</a>.</li>
<li>When creating a signature, the salt length is equal to the length of the hash, or the largest possible salt length for the algorithm and key size if that is smaller than the hash length.</li>
<li>When verifying a signature, any salt length permitted by the RSASSA-PSS signature algorithm is accepted.</li>
<li>The specified hash algorithm is used to hash the input message, to create the salted hash, and for the mask generation.</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <a class="reference internal" href="#c.PSA_ALG_RSA_PSS" title="PSA_ALG_RSA_PSS"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_RSA_PSS()</span></code></a> algorithm is equivalent to <a class="reference internal" href="#c.PSA_ALG_RSA_PSS_ANY_SALT" title="PSA_ALG_RSA_PSS_ANY_SALT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_RSA_PSS_ANY_SALT()</span></code></a> when creating a signature, but is strict about the permitted salt length when verifying a signature.</p>
</div>
<p class="rubric">Compatible key types</p>
<div class="line-block">
<div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_RSA_KEY_PAIR" title="PSA_KEY_TYPE_RSA_KEY_PAIR"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_RSA_KEY_PAIR</span></code></a></div>
<div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_RSA_PUBLIC_KEY" title="PSA_KEY_TYPE_RSA_PUBLIC_KEY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_RSA_PUBLIC_KEY</span></code></a> (signature verification only)</div>
</div>
</div>
<div class="section" id="PSA_ALG_ECDSA">
<span id="c.PSA_ALG_ECDSA"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code> (macro)</h3>
<p>The randomized ECDSA signature scheme, with hashing.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA">PSA_ALG_ECDSA</a>(hash_alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
<dd>A hash algorithm: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true. This includes <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a> when specifying the algorithm in a key policy.</dd>
</dl>
<p class="rubric">Returns</p>
<p>The corresponding randomized ECDSA signature algorithm.</p>
<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
<p class="rubric">Description</p>
<p>This algorithm can be used with both the message and hash signature functions.</p>
<p>This algorithm is randomized: each invocation returns a different, equally valid signature.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>When based on the same hash algorithm, the verification operations for <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a> and <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a> are identical. A signature created using <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a> can be verified with the same key using either <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a> or <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a>. Similarly, a signature created using <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a> can be verified with the same key using either <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a> or <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a>.</p>
<p class="last">In particular, it is impossible to determine whether a signature was produced with deterministic ECDSA or with randomized ECDSA: it is only possible to verify that a signature was made with ECDSA with the private key corresponding to the public key used for the verification.</p>
</div>
<p>This signature scheme is defined by <span><em>SEC 1: Elliptic Curve Cryptography</em> <a class="reference internal" href="../../about.html#citation-sec1"><span class="cite">[SEC1]</span></a></span>, and also by <span><em>Public Key Cryptography For The Financial Services Industry: The Elliptic Curve Digital Signature Algorithm (ECDSA)</em> <a class="reference internal" href="../../about.html#citation-x9-62"><span class="cite">[X9-62]</span></a></span>, with a random per-message secret number <em>k</em>.</p>
<p>The representation of the signature as a byte string consists of the concatenation of the signature values <em>r</em> and <em>s</em>. Each of <em>r</em> and <em>s</em> is encoded as an <em>N</em>-octet string, where <em>N</em> is the length of the base point of the curve in octets. Each value is represented in big-endian order, with the most significant octet first.</p>
<p class="rubric">Compatible key types</p>
<div class="line-block">
<div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ECC_KEY_PAIR" title="PSA_KEY_TYPE_ECC_KEY_PAIR"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_ECC_KEY_PAIR</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">family</span></code><code class="docutils literal"><span class="pre">)</span></code></div>
<div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ECC_PUBLIC_KEY" title="PSA_KEY_TYPE_ECC_PUBLIC_KEY"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_ECC_PUBLIC_KEY</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">family</span></code><code class="docutils literal"><span class="pre">)</span></code> (signature verification only)</div>
</div>
<p>where <code class="docutils literal"><span class="pre">family</span></code> is a Weierstrass Elliptic curve family. That is, one of the following values:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_SECT_XX</span></code></li>
<li><code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_SECP_XX</span></code></li>
<li><a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_FRP" title="PSA_ECC_FAMILY_FRP"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_FRP</span></code></a></li>
<li><a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_BRAINPOOL_P_R1" title="PSA_ECC_FAMILY_BRAINPOOL_P_R1"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_BRAINPOOL_P_R1</span></code></a></li>
</ul>
</div>
<div class="section" id="PSA_ALG_ECDSA_ANY">
<span id="c.PSA_ALG_ECDSA_ANY"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_ECDSA_ANY</span></code> (macro)</h3>
<p>The randomized ECDSA signature scheme, without hashing.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_ECDSA_ANY" title="PSA_ALG_ECDSA_ANY">PSA_ALG_ECDSA_ANY</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>) 0x06000600)
</pre>
<p>This algorithm can be only used with the <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a> and <a class="reference internal" href="#c.psa_verify_hash" title="psa_verify_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_hash()</span></code></a> functions.</p>
<p>This algorithm is randomized: each invocation returns a different, equally valid signature.</p>
<p>This is the same signature scheme as <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA()</span></code></a>, but without specifying a hash algorithm, and skipping the message hashing operation.</p>
<p>This algorithm is only recommended to sign or verify a sequence of bytes that are an already-calculated hash. Note that the input is padded with zeros on the left or truncated on the right as required to fit the curve size.</p>
<p class="rubric">Compatible key types</p>
<div class="line-block">
<div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ECC_KEY_PAIR" title="PSA_KEY_TYPE_ECC_KEY_PAIR"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_ECC_KEY_PAIR</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">family</span></code><code class="docutils literal"><span class="pre">)</span></code></div>
<div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ECC_PUBLIC_KEY" title="PSA_KEY_TYPE_ECC_PUBLIC_KEY"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_ECC_PUBLIC_KEY</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">family</span></code><code class="docutils literal"><span class="pre">)</span></code> (signature verification only)</div>
</div>
<p>where <code class="docutils literal"><span class="pre">family</span></code> is a Weierstrass Elliptic curve family. That is, one of the following values:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_SECT_XX</span></code></li>
<li><code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_SECP_XX</span></code></li>
<li><a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_FRP" title="PSA_ECC_FAMILY_FRP"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_FRP</span></code></a></li>
<li><a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_BRAINPOOL_P_R1" title="PSA_ECC_FAMILY_BRAINPOOL_P_R1"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_BRAINPOOL_P_R1</span></code></a></li>
</ul>
</div>
<div class="section" id="PSA_ALG_DETERMINISTIC_ECDSA">
<span id="c.PSA_ALG_DETERMINISTIC_ECDSA"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code> (macro)</h3>
<p>Deterministic ECDSA signature scheme, with hashing.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA">PSA_ALG_DETERMINISTIC_ECDSA</a>(hash_alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
<dd>A hash algorithm: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true. This includes <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a> when specifying the algorithm in a key policy.</dd>
</dl>
<p class="rubric">Returns</p>
<p>The corresponding deterministic ECDSA signature algorithm.</p>
<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
<p class="rubric">Description</p>
<p>This algorithm can be used with both the message and hash signature functions.</p>
<p>This is the deterministic ECDSA signature scheme defined by <span><em>Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA)</em> <a class="reference internal" href="../../about.html#citation-rfc6979"><span class="cite">[RFC6979]</span></a></span>.</p>
<p>The representation of a signature is the same as with <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA()</span></code></a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>When based on the same hash algorithm, the verification operations for <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a> and <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a> are identical. A signature created using <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a> can be verified with the same key using either <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a> or <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a>. Similarly, a signature created using <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a> can be verified with the same key using either <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a> or <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a>.</p>
<p class="last">In particular, it is impossible to determine whether a signature was produced with deterministic ECDSA or with randomized ECDSA: it is only possible to verify that a signature was made with ECDSA with the private key corresponding to the public key used for the verification.</p>
</div>
<p class="rubric">Compatible key types</p>
<div class="line-block">
<div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ECC_KEY_PAIR" title="PSA_KEY_TYPE_ECC_KEY_PAIR"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_ECC_KEY_PAIR</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">family</span></code><code class="docutils literal"><span class="pre">)</span></code></div>
<div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ECC_PUBLIC_KEY" title="PSA_KEY_TYPE_ECC_PUBLIC_KEY"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_ECC_PUBLIC_KEY</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">family</span></code><code class="docutils literal"><span class="pre">)</span></code> (signature verification only)</div>
</div>
<p>where <code class="docutils literal"><span class="pre">family</span></code> is a Weierstrass Elliptic curve family. That is, one of the following values:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_SECT_XX</span></code></li>
<li><code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_SECP_XX</span></code></li>
<li><a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_FRP" title="PSA_ECC_FAMILY_FRP"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_FRP</span></code></a></li>
<li><a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_BRAINPOOL_P_R1" title="PSA_ECC_FAMILY_BRAINPOOL_P_R1"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_BRAINPOOL_P_R1</span></code></a></li>
</ul>
</div>
<div class="section" id="PSA_ALG_PURE_EDDSA">
<span id="c.PSA_ALG_PURE_EDDSA"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_PURE_EDDSA</span></code> (macro)</h3>
<p>Edwards-curve digital signature algorithm without prehashing (PureEdDSA), using standard parameters.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_PURE_EDDSA" title="PSA_ALG_PURE_EDDSA">PSA_ALG_PURE_EDDSA</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>) 0x06000800)
</pre>
<p>This algorithm can be only used with the <a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_message()</span></code></a> and <a class="reference internal" href="#c.psa_verify_message" title="psa_verify_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_message()</span></code></a> functions.</p>
<p>This is the PureEdDSA digital signature algorithm defined by <span><em>Edwards-Curve Digital Signature Algorithm (EdDSA)</em> <a class="reference internal" href="../../about.html#citation-rfc8032"><span class="cite">[RFC8032]</span></a></span>, using standard parameters.</p>
<p>PureEdDSA requires an elliptic curve key on a twisted Edwards curve. The following curves are supported:</p>
<ul class="simple">
<li>Edwards25519: the Ed25519 algorithm is computed. The output signature is a 64-byte string: the concatenation of <em>R</em> and <em>S</em> as defined by <a class="reference internal" href="../../about.html#citation-rfc8032"><span class="cite">[RFC8032]</span></a> <a class="reference external" href="https://tools.ietf.org/html/rfc8032.html#section-5.1.6">§5.1.6</a>.</li>
<li>Edwards448: the Ed448 algorithm is computed with an empty string as the context. The output signature is a 114-byte string: the concatenation of <em>R</em> and <em>S</em> as defined by <a class="reference internal" href="../../about.html#citation-rfc8032"><span class="cite">[RFC8032]</span></a> <a class="reference external" href="https://tools.ietf.org/html/rfc8032.html#section-5.2.6">§5.2.6</a>.</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Contexts are not supported in the current version of this specification because there is no suitable signature interface that can take the context as a parameter. A future version of this specification may add suitable functions and extend this algorithm to support contexts.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>To sign or verify the pre-computed hash of a message using EdDSA, the HashEdDSA algorithms (<a class="reference internal" href="#c.PSA_ALG_ED25519PH" title="PSA_ALG_ED25519PH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ED25519PH</span></code></a> and <a class="reference internal" href="#c.PSA_ALG_ED448PH" title="PSA_ALG_ED448PH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ED448PH</span></code></a>) can be used with <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a> and <a class="reference internal" href="#c.psa_verify_hash" title="psa_verify_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_hash()</span></code></a>.</p>
<p class="last">The signature produced by HashEdDSA is distinct from that produced by PureEdDSA.</p>
</div>
<p class="rubric">Compatible key types</p>
<div class="line-block">
<div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ECC_KEY_PAIR" title="PSA_KEY_TYPE_ECC_KEY_PAIR"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_ECC_KEY_PAIR</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_TWISTED_EDWARDS" title="PSA_ECC_FAMILY_TWISTED_EDWARDS"><code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_TWISTED_EDWARDS</span></code></a><code class="docutils literal"><span class="pre">)</span></code></div>
<div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ECC_PUBLIC_KEY" title="PSA_KEY_TYPE_ECC_PUBLIC_KEY"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_ECC_PUBLIC_KEY</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_TWISTED_EDWARDS" title="PSA_ECC_FAMILY_TWISTED_EDWARDS"><code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_TWISTED_EDWARDS</span></code></a><code class="docutils literal"><span class="pre">)</span></code> (signature verification only)</div>
</div>
</div>
<div class="section" id="PSA_ALG_ED25519PH">
<span id="c.PSA_ALG_ED25519PH"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_ED25519PH</span></code> (macro)</h3>
<p>Edwards-curve digital signature algorithm with prehashing (HashEdDSA), using the Edwards25519 curve.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_ED25519PH" title="PSA_ALG_ED25519PH">PSA_ALG_ED25519PH</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>) 0x0600090B)
</pre>
<p>This algorithm can be used with both the message and hash signature functions.</p>
<p>This computes the Ed25519ph algorithm as specified in <span><em>Edwards-Curve Digital Signature Algorithm (EdDSA)</em> <a class="reference internal" href="../../about.html#citation-rfc8032"><span class="cite">[RFC8032]</span></a></span> <a class="reference external" href="https://tools.ietf.org/html/rfc8032.html#section-5.1">§5.1</a>, and requires an Edwards25519 curve key. An empty string is used as the context. The prehash function is SHA-512.</p>
<div class="admonition-implementation-note admonition">
<p class="first admonition-title">Implementation note</p>
<p class="last">When used with <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a> or <a class="reference internal" href="#c.psa_verify_hash" title="psa_verify_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_hash()</span></code></a>, the <code class="docutils literal"><span class="pre">hash</span></code> parameter to the call should be used as <code class="docutils literal"><span class="pre">PH(M)</span></code> in the algorithms defined in <a class="reference internal" href="../../about.html#citation-rfc8032"><span class="cite">[RFC8032]</span></a> <a class="reference external" href="https://tools.ietf.org/html/rfc8032.html#section-5.1">§5.1</a>.</p>
</div>
<p class="rubric">Usage</p>
<p>This is a hash-and-sign algorithm. To calculate a signature, use one of the following approaches:</p>
<ul class="simple">
<li>Call <a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_message()</span></code></a> with the message.</li>
<li>Calculate the SHA-512 hash of the message with <a class="reference internal" href="hashes.html#c.psa_hash_compute" title="psa_hash_compute"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_compute()</span></code></a>, or with a multi-part hash operation, using the hash algorithm <a class="reference internal" href="hashes.html#c.PSA_ALG_SHA_512" title="PSA_ALG_SHA_512"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_SHA_512</span></code></a>. Then sign the calculated hash with <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a>.</li>
</ul>
<p>Verifying a signature is similar, using <a class="reference internal" href="#c.psa_verify_message" title="psa_verify_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_message()</span></code></a> or <a class="reference internal" href="#c.psa_verify_hash" title="psa_verify_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_hash()</span></code></a> instead of the signature function.</p>
<p class="rubric">Compatible key types</p>
<div class="line-block">
<div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ECC_KEY_PAIR" title="PSA_KEY_TYPE_ECC_KEY_PAIR"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_ECC_KEY_PAIR</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_TWISTED_EDWARDS" title="PSA_ECC_FAMILY_TWISTED_EDWARDS"><code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_TWISTED_EDWARDS</span></code></a><code class="docutils literal"><span class="pre">)</span></code></div>
<div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ECC_PUBLIC_KEY" title="PSA_KEY_TYPE_ECC_PUBLIC_KEY"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_ECC_PUBLIC_KEY</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_TWISTED_EDWARDS" title="PSA_ECC_FAMILY_TWISTED_EDWARDS"><code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_TWISTED_EDWARDS</span></code></a><code class="docutils literal"><span class="pre">)</span></code> (signature verification only)</div>
</div>
</div>
<div class="section" id="PSA_ALG_ED448PH">
<span id="c.PSA_ALG_ED448PH"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_ED448PH</span></code> (macro)</h3>
<p>Edwards-curve digital signature algorithm with prehashing (HashEdDSA), using the Edwards448 curve.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_ED448PH" title="PSA_ALG_ED448PH">PSA_ALG_ED448PH</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>) 0x06000915)
</pre>
<p>This algorithm can be used with both the message and hash signature functions.</p>
<p>This computes the Ed448ph algorithm as specified in <span><em>Edwards-Curve Digital Signature Algorithm (EdDSA)</em> <a class="reference internal" href="../../about.html#citation-rfc8032"><span class="cite">[RFC8032]</span></a></span> <a class="reference external" href="https://tools.ietf.org/html/rfc8032.html#section-5.2">§5.2</a>, and requires an Edwards448 curve key. An empty string is used as the context. The prehash function is the first 64 bytes of the output from SHAKE256.</p>
<div class="admonition-implementation-note admonition">
<p class="first admonition-title">Implementation note</p>
<p class="last">When used with <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a> or <a class="reference internal" href="#c.psa_verify_hash" title="psa_verify_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_hash()</span></code></a>, the <code class="docutils literal"><span class="pre">hash</span></code> parameter to the call should be used as <code class="docutils literal"><span class="pre">PH(M)</span></code> in the algorithms defined in <a class="reference internal" href="../../about.html#citation-rfc8032"><span class="cite">[RFC8032]</span></a> <a class="reference external" href="https://tools.ietf.org/html/rfc8032.html#section-5.2">§5.2</a>.</p>
</div>
<p class="rubric">Usage</p>
<p>This is a hash-and-sign algorithm. To calculate a signature, use one of the following approaches:</p>
<ul class="simple">
<li>Call <a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_message()</span></code></a> with the message.</li>
<li>Calculate the first 64 bytes of the SHAKE256 output of the message with <a class="reference internal" href="hashes.html#c.psa_hash_compute" title="psa_hash_compute"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_compute()</span></code></a>, or with a multi-part hash operation, using the hash algorithm <a class="reference internal" href="hashes.html#c.PSA_ALG_SHAKE256_512" title="PSA_ALG_SHAKE256_512"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_SHAKE256_512</span></code></a>. Then sign the calculated hash with <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a>.</li>
</ul>
<p>Verifying a signature is similar, using <a class="reference internal" href="#c.psa_verify_message" title="psa_verify_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_message()</span></code></a> or <a class="reference internal" href="#c.psa_verify_hash" title="psa_verify_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_hash()</span></code></a> instead of the signature function.</p>
<p class="rubric">Compatible key types</p>
<div class="line-block">
<div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ECC_KEY_PAIR" title="PSA_KEY_TYPE_ECC_KEY_PAIR"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_ECC_KEY_PAIR</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_TWISTED_EDWARDS" title="PSA_ECC_FAMILY_TWISTED_EDWARDS"><code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_TWISTED_EDWARDS</span></code></a><code class="docutils literal"><span class="pre">)</span></code></div>
<div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ECC_PUBLIC_KEY" title="PSA_KEY_TYPE_ECC_PUBLIC_KEY"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_ECC_PUBLIC_KEY</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_TWISTED_EDWARDS" title="PSA_ECC_FAMILY_TWISTED_EDWARDS"><code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_TWISTED_EDWARDS</span></code></a><code class="docutils literal"><span class="pre">)</span></code> (signature verification only)</div>
</div>
</div>
</div>
<div class="section" id="asymmetric-signature-functions">
<h2>10.7.2. Asymmetric signature functions</h2>
<div class="section" id="psa_sign_message">
<span id="c.psa_sign_message"></span><h3><code class="docutils literal"><span class="pre">psa_sign_message</span></code> (function)</h3>
<p>Sign a message with a private key. For hash-and-sign algorithms, this includes the hashing step.</p>
<pre class="literal-block">
<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message">psa_sign_message</a>(<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
                              <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
                              const uint8_t * input,
                              size_t input_length,
                              uint8_t * signature,
                              size_t signature_size,
                              size_t * signature_length);
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
<dd>Identifier of the key to use for the operation. It must be an asymmetric key pair. The key must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_SIGN_MESSAGE" title="PSA_KEY_USAGE_SIGN_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_MESSAGE</span></code></a>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>An asymmetric signature algorithm: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="#c.PSA_ALG_IS_SIGN_MESSAGE" title="PSA_ALG_IS_SIGN_MESSAGE"><code class="docutils literal"><span class="pre">PSA_ALG_IS_SIGN_MESSAGE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</dd>
<dt> <code class="docutils literal"><span class="pre">input</span></code></dt>
<dd>The input message to sign.</dd>
<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
<dd>Size of the <code class="docutils literal"><span class="pre">input</span></code> buffer in bytes.</dd>
<dt> <code class="docutils literal"><span class="pre">signature</span></code></dt>
<dd>Buffer where the signature is to be written.</dd>
<dt> <code class="docutils literal"><span class="pre">signature_size</span></code></dt>
<dd><p class="first">Size of the <code class="docutils literal"><span class="pre">signature</span></code> buffer in bytes.
This must be appropriate for the selected algorithm and key:</p>
<ul class="last simple">
<li>The required signature size is <a class="reference internal" href="#c.PSA_SIGN_OUTPUT_SIZE" title="PSA_SIGN_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_SIGN_OUTPUT_SIZE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">key_type</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">key_bits</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">key_type</span></code> and <code class="docutils literal"><span class="pre">key_bits</span></code> are the type and bit-size respectively of <code class="docutils literal"><span class="pre">key</span></code>.</li>
<li><a class="reference internal" href="#c.PSA_SIGNATURE_MAX_SIZE" title="PSA_SIGNATURE_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SIGNATURE_MAX_SIZE</span></code></a> evaluates to the maximum signature size of any supported signature algorithm.</li>
</ul>
</dd>
<dt> <code class="docutils literal"><span class="pre">signature_length</span></code></dt>
<dd>On success, the number of bytes that make up the returned signature value.</dd>
</dl>
<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
<dl class="docutils">
<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
<dd>Success.
The first <code class="docutils literal"><span class="pre">(*signature_length)</span></code> bytes of <code class="docutils literal"><span class="pre">signature</span></code> contain the signature value.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
<dd>The library requires initializing by a call to <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">key</span></code> is not a valid key identifier.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_SIGN_MESSAGE" title="PSA_KEY_USAGE_SIGN_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_MESSAGE</span></code></a> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt>
<dd>The size of the <code class="docutils literal"><span class="pre">signature</span></code> buffer is too small.
<a class="reference internal" href="#c.PSA_SIGN_OUTPUT_SIZE" title="PSA_SIGN_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SIGN_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_SIGNATURE_MAX_SIZE" title="PSA_SIGNATURE_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SIGNATURE_MAX_SIZE</span></code></a> can be used to determine a sufficient buffer size.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
<dd><p class="first">The following conditions can result in this error:</p>
<ul class="last simple">
<li><code class="docutils literal"><span class="pre">alg</span></code> is not an asymmetric signature algorithm.</li>
<li><code class="docutils literal"><span class="pre">key</span></code> is not an asymmetric key pair, that is compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</li>
<li><code class="docutils literal"><span class="pre">input_length</span></code> is too large for the algorithm and key type.</li>
</ul>
</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
<dd><p class="first">The following conditions can result in this error:</p>
<ul class="last simple">
<li><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not an asymmetric signature algorithm.</li>
<li><code class="docutils literal"><span class="pre">key</span></code> is not supported for use with <code class="docutils literal"><span class="pre">alg</span></code>.</li>
<li><code class="docutils literal"><span class="pre">input_length</span></code> is too large for the implementation.</li>
</ul>
</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_ENTROPY" title="PSA_ERROR_INSUFFICIENT_ENTROPY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_ENTROPY</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
<dd></dd>
</dl>
<p class="rubric">Description</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">To perform a multi-part hash-and-sign signature algorithm, first use a <a class="reference internal" href="hashes.html#hash-mp"><span class="std std-ref">multi-part hash operation</span></a> and then pass the resulting hash to <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a>. <a class="reference internal" href="algorithms.html#c.PSA_ALG_GET_HASH" title="PSA_ALG_GET_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_GET_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> can be used to determine the hash algorithm to use.</p>
</div>
</div>
<div class="section" id="psa_verify_message">
<span id="c.psa_verify_message"></span><h3><code class="docutils literal"><span class="pre">psa_verify_message</span></code> (function)</h3>
<p>Verify the signature of a message with a public key. For hash-and-sign algorithms, this includes the hashing step.</p>
<pre class="literal-block">
<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_verify_message" title="psa_verify_message">psa_verify_message</a>(<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
                                <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
                                const uint8_t * input,
                                size_t input_length,
                                const uint8_t * signature,
                                size_t signature_length);
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
<dd>Identifier of the key to use for the operation. It must be a public key or an asymmetric key pair. The key must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code></a>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>An asymmetric signature algorithm: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="#c.PSA_ALG_IS_SIGN_MESSAGE" title="PSA_ALG_IS_SIGN_MESSAGE"><code class="docutils literal"><span class="pre">PSA_ALG_IS_SIGN_MESSAGE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</dd>
<dt> <code class="docutils literal"><span class="pre">input</span></code></dt>
<dd>The message whose signature is to be verified.</dd>
<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
<dd>Size of the <code class="docutils literal"><span class="pre">input</span></code> buffer in bytes.</dd>
<dt> <code class="docutils literal"><span class="pre">signature</span></code></dt>
<dd>Buffer containing the signature to verify.</dd>
<dt> <code class="docutils literal"><span class="pre">signature_length</span></code></dt>
<dd>Size of the <code class="docutils literal"><span class="pre">signature</span></code> buffer in bytes.</dd>
</dl>
<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
<dl class="docutils">
<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
<dd>Success.
The signature is valid.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
<dd>The library requires initializing by a call to <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">key</span></code> is not a valid key identifier.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code></a> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_SIGNATURE" title="PSA_ERROR_INVALID_SIGNATURE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_SIGNATURE</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">signature</span></code> is not the result of signing the <code class="docutils literal"><span class="pre">input</span></code> message with algorithm <code class="docutils literal"><span class="pre">alg</span></code> using the private key corresponding to <code class="docutils literal"><span class="pre">key</span></code>.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
<dd><p class="first">The following conditions can result in this error:</p>
<ul class="last simple">
<li><code class="docutils literal"><span class="pre">alg</span></code> is not an asymmetric signature algorithm.</li>
<li><code class="docutils literal"><span class="pre">key</span></code> is not a public key or an asymmetric key pair, that is compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</li>
<li><code class="docutils literal"><span class="pre">input_length</span></code> is too large for the algorithm and key type.</li>
</ul>
</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
<dd><p class="first">The following conditions can result in this error:</p>
<ul class="last simple">
<li><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not an asymmetric signature algorithm.</li>
<li><code class="docutils literal"><span class="pre">key</span></code> is not supported for use with <code class="docutils literal"><span class="pre">alg</span></code>.</li>
<li><code class="docutils literal"><span class="pre">input_length</span></code> is too large for the implementation.</li>
</ul>
</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
<dd></dd>
</dl>
<p class="rubric">Description</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">To perform a multi-part hash-and-sign signature verification algorithm, first use a <a class="reference internal" href="hashes.html#hash-mp"><span class="std std-ref">multi-part hash operation</span></a> to hash the message and then pass the resulting hash to <a class="reference internal" href="#c.psa_verify_hash" title="psa_verify_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_hash()</span></code></a>. <a class="reference internal" href="algorithms.html#c.PSA_ALG_GET_HASH" title="PSA_ALG_GET_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_GET_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> can be used to determine the hash algorithm to use.</p>
</div>
</div>
<div class="section" id="psa_sign_hash">
<span id="c.psa_sign_hash"></span><h3><code class="docutils literal"><span class="pre">psa_sign_hash</span></code> (function)</h3>
<p>Sign an already-calculated hash with a private key.</p>
<pre class="literal-block">
<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash">psa_sign_hash</a>(<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
                           <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
                           const uint8_t * hash,
                           size_t hash_length,
                           uint8_t * signature,
                           size_t signature_size,
                           size_t * signature_length);
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
<dd>Identifier of the key to use for the operation. It must be an asymmetric key pair. The key must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_SIGN_HASH" title="PSA_KEY_USAGE_SIGN_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_HASH</span></code></a>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>An asymmetric signature algorithm that separates the hash and sign operations: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="#c.PSA_ALG_IS_SIGN_HASH" title="PSA_ALG_IS_SIGN_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_SIGN_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</dd>
<dt> <code class="docutils literal"><span class="pre">hash</span></code></dt>
<dd>The input to sign. This is usually the hash of a message. See the detailed description of this function and the description of individual signature algorithms for a detailed description of acceptable inputs.</dd>
<dt> <code class="docutils literal"><span class="pre">hash_length</span></code></dt>
<dd>Size of the <code class="docutils literal"><span class="pre">hash</span></code> buffer in bytes.</dd>
<dt> <code class="docutils literal"><span class="pre">signature</span></code></dt>
<dd>Buffer where the signature is to be written.</dd>
<dt> <code class="docutils literal"><span class="pre">signature_size</span></code></dt>
<dd><p class="first">Size of the <code class="docutils literal"><span class="pre">signature</span></code> buffer in bytes.
This must be appropriate for the selected algorithm and key:</p>
<ul class="last simple">
<li>The required signature size is <a class="reference internal" href="#c.PSA_SIGN_OUTPUT_SIZE" title="PSA_SIGN_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_SIGN_OUTPUT_SIZE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">key_type</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">key_bits</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">key_type</span></code> and <code class="docutils literal"><span class="pre">key_bits</span></code> are the type and bit-size respectively of <code class="docutils literal"><span class="pre">key</span></code>.</li>
<li><a class="reference internal" href="#c.PSA_SIGNATURE_MAX_SIZE" title="PSA_SIGNATURE_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SIGNATURE_MAX_SIZE</span></code></a> evaluates to the maximum signature size of any supported signature algorithm.</li>
</ul>
</dd>
<dt> <code class="docutils literal"><span class="pre">signature_length</span></code></dt>
<dd>On success, the number of bytes that make up the returned signature value.</dd>
</dl>
<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
<dl class="docutils">
<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
<dd>Success.
The first <code class="docutils literal"><span class="pre">(*signature_length)</span></code> bytes of <code class="docutils literal"><span class="pre">signature</span></code> contain the signature value.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
<dd>The library requires initializing by a call to <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">key</span></code> is not a valid key identifier.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_SIGN_HASH" title="PSA_KEY_USAGE_SIGN_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_HASH</span></code></a> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt>
<dd>The size of the <code class="docutils literal"><span class="pre">signature</span></code> buffer is too small.
<a class="reference internal" href="#c.PSA_SIGN_OUTPUT_SIZE" title="PSA_SIGN_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SIGN_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_SIGNATURE_MAX_SIZE" title="PSA_SIGNATURE_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SIGNATURE_MAX_SIZE</span></code></a> can be used to determine a sufficient buffer size.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
<dd><p class="first">The following conditions can result in this error:</p>
<ul class="last simple">
<li><code class="docutils literal"><span class="pre">alg</span></code> is not an asymmetric signature algorithm.</li>
<li><code class="docutils literal"><span class="pre">key</span></code> is not an asymmetric key pair, that is compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</li>
<li><code class="docutils literal"><span class="pre">hash_length</span></code> is not valid for the algorithm and key type.</li>
</ul>
</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
<dd><p class="first">The following conditions can result in this error:</p>
<ul class="last simple">
<li><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not an asymmetric signature algorithm.</li>
<li><code class="docutils literal"><span class="pre">key</span></code> is not supported for use with <code class="docutils literal"><span class="pre">alg</span></code>.</li>
</ul>
</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_ENTROPY" title="PSA_ERROR_INSUFFICIENT_ENTROPY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_ENTROPY</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
<dd></dd>
</dl>
<p class="rubric">Description</p>
<p>With most signature mechanisms that follow the hash-and-sign paradigm, the hash input to this function is the hash of the message to sign. The hash algorithm is encoded in the signature algorithm.</p>
<p>Some hash-and-sign mechanisms apply a padding or encoding to the hash. In such cases, the encoded hash must be passed to this function. The current version of this specification defines one such signature algorithm: <a class="reference internal" href="#c.PSA_ALG_RSA_PKCS1V15_SIGN_RAW" title="PSA_ALG_RSA_PKCS1V15_SIGN_RAW"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_RSA_PKCS1V15_SIGN_RAW</span></code></a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>To perform a hash-and-sign signature algorithm, the hash must be calculated before passing it to this function. This can be done by calling <a class="reference internal" href="hashes.html#c.psa_hash_compute" title="psa_hash_compute"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_compute()</span></code></a> or with a multi-part hash operation. The correct hash algorithm to use can be determined using <a class="reference internal" href="algorithms.html#c.PSA_ALG_GET_HASH" title="PSA_ALG_GET_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_GET_HASH()</span></code></a>.</p>
<p class="last">Alternatively, to hash and sign a message in a single call, use <a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_message()</span></code></a>.</p>
</div>
</div>
<div class="section" id="psa_verify_hash">
<span id="c.psa_verify_hash"></span><h3><code class="docutils literal"><span class="pre">psa_verify_hash</span></code> (function)</h3>
<p>Verify the signature of a hash or short message using a public key.</p>
<pre class="literal-block">
<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_verify_hash" title="psa_verify_hash">psa_verify_hash</a>(<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
                             <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
                             const uint8_t * hash,
                             size_t hash_length,
                             const uint8_t * signature,
                             size_t signature_length);
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
<dd>Identifier of the key to use for the operation. It must be a public key or an asymmetric key pair. The key must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_VERIFY_HASH" title="PSA_KEY_USAGE_VERIFY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_HASH</span></code></a>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>An asymmetric signature algorithm that separates the hash and sign operations: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="#c.PSA_ALG_IS_SIGN_HASH" title="PSA_ALG_IS_SIGN_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_SIGN_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</dd>
<dt> <code class="docutils literal"><span class="pre">hash</span></code></dt>
<dd>The input whose signature is to be verified. This is usually the hash of a message. See the detailed description of this function and the description of individual signature algorithms for a detailed description of acceptable inputs.</dd>
<dt> <code class="docutils literal"><span class="pre">hash_length</span></code></dt>
<dd>Size of the <code class="docutils literal"><span class="pre">hash</span></code> buffer in bytes.</dd>
<dt> <code class="docutils literal"><span class="pre">signature</span></code></dt>
<dd>Buffer containing the signature to verify.</dd>
<dt> <code class="docutils literal"><span class="pre">signature_length</span></code></dt>
<dd>Size of the <code class="docutils literal"><span class="pre">signature</span></code> buffer in bytes.</dd>
</dl>
<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
<dl class="docutils">
<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
<dd>Success.
The signature is valid.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
<dd>The library requires initializing by a call to <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">key</span></code> is not a valid key identifier.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_VERIFY_HASH" title="PSA_KEY_USAGE_VERIFY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_HASH</span></code></a> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_SIGNATURE" title="PSA_ERROR_INVALID_SIGNATURE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_SIGNATURE</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">signature</span></code> is not the result of signing <code class="docutils literal"><span class="pre">hash</span></code> with algorithm <code class="docutils literal"><span class="pre">alg</span></code> using the private key corresponding to <code class="docutils literal"><span class="pre">key</span></code>.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
<dd><p class="first">The following conditions can result in this error:</p>
<ul class="last simple">
<li><code class="docutils literal"><span class="pre">alg</span></code> is not an asymmetric signature algorithm.</li>
<li><code class="docutils literal"><span class="pre">key</span></code> is not a public key or an asymmetric key pair, that is compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</li>
<li><code class="docutils literal"><span class="pre">hash_length</span></code> is not valid for the algorithm and key type.</li>
</ul>
</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
<dd><p class="first">The following conditions can result in this error:</p>
<ul class="last simple">
<li><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not an asymmetric signature algorithm.</li>
<li><code class="docutils literal"><span class="pre">key</span></code> is not supported for use with <code class="docutils literal"><span class="pre">alg</span></code>.</li>
</ul>
</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
<dd></dd>
</dl>
<p class="rubric">Description</p>
<p>With most signature mechanisms that follow the hash-and-sign paradigm, the hash input to this function is the hash of the message to sign. The hash algorithm is encoded in the signature algorithm.</p>
<p>Some hash-and-sign mechanisms apply a padding or encoding to the hash. In such cases, the encoded hash must be passed to this function. The current version of this specification defines one such signature algorithm: <a class="reference internal" href="#c.PSA_ALG_RSA_PKCS1V15_SIGN_RAW" title="PSA_ALG_RSA_PKCS1V15_SIGN_RAW"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_RSA_PKCS1V15_SIGN_RAW</span></code></a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>To perform a hash-and-sign verification algorithm, the hash must be calculated before passing it to this function. This can be done by calling <a class="reference internal" href="hashes.html#c.psa_hash_compute" title="psa_hash_compute"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_compute()</span></code></a> or with a multi-part hash operation. The correct hash algorithm to use can be determined using <a class="reference internal" href="algorithms.html#c.PSA_ALG_GET_HASH" title="PSA_ALG_GET_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_GET_HASH()</span></code></a>.</p>
<p class="last">Alternatively, to hash and verify a message in a single call, use <a class="reference internal" href="#c.psa_verify_message" title="psa_verify_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_message()</span></code></a>.</p>
</div>
</div>
</div>
<div class="section" id="support-macros">
<h2>10.7.3. Support macros</h2>
<div class="section" id="PSA_ALG_IS_SIGN_MESSAGE">
<span id="c.PSA_ALG_IS_SIGN_MESSAGE"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_SIGN_MESSAGE</span></code> (macro)</h3>
<p>Whether the specified algorithm is a signature algorithm that can be used with <a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_message()</span></code></a> and <a class="reference internal" href="#c.psa_verify_message" title="psa_verify_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_message()</span></code></a>.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_IS_SIGN_MESSAGE" title="PSA_ALG_IS_SIGN_MESSAGE">PSA_ALG_IS_SIGN_MESSAGE</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>An algorithm identifier: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>.</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a signature algorithm that can be used to sign a message. <code class="docutils literal"><span class="pre">0</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a signature algorithm that can only be used to sign an already-calculated hash. <code class="docutils literal"><span class="pre">0</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a signature algorithm. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
</div>
<div class="section" id="PSA_ALG_IS_SIGN_HASH">
<span id="c.PSA_ALG_IS_SIGN_HASH"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_SIGN_HASH</span></code> (macro)</h3>
<p>Whether the specified algorithm is a signature algorithm that can be used with <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a> and <a class="reference internal" href="#c.psa_verify_hash" title="psa_verify_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_hash()</span></code></a>.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_IS_SIGN_HASH" title="PSA_ALG_IS_SIGN_HASH">PSA_ALG_IS_SIGN_HASH</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>An algorithm identifier: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>.</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a signature algorithm that can be used to sign a hash. <code class="docutils literal"><span class="pre">0</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a signature algorithm that can only be used to sign a message. <code class="docutils literal"><span class="pre">0</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a signature algorithm. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
<p class="rubric">Description</p>
<p>This includes all algorithms such that <a class="reference internal" href="#c.PSA_ALG_IS_HASH_AND_SIGN" title="PSA_ALG_IS_HASH_AND_SIGN"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_IS_HASH_AND_SIGN()</span></code></a> is true, as well as signature algorithms for which the input to <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a> or <a class="reference internal" href="#c.psa_verify_hash" title="psa_verify_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_hash()</span></code></a> is not directly a hash, such as <a class="reference internal" href="#c.PSA_ALG_IS_RSA_PKCS1V15_SIGN" title="PSA_ALG_IS_RSA_PKCS1V15_SIGN"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_IS_RSA_PKCS1V15_SIGN</span></code></a>.</p>
</div>
<div class="section" id="PSA_ALG_IS_RSA_PKCS1V15_SIGN">
<span id="c.PSA_ALG_IS_RSA_PKCS1V15_SIGN"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_RSA_PKCS1V15_SIGN</span></code> (macro)</h3>
<p>Whether the specified algorithm is an RSA PKCS#1 v1.5 signature algorithm.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_IS_RSA_PKCS1V15_SIGN" title="PSA_ALG_IS_RSA_PKCS1V15_SIGN">PSA_ALG_IS_RSA_PKCS1V15_SIGN</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>An algorithm identifier: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>.</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is an RSA PKCS#1 v1.5 signature algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise.</p>
<p>This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
</div>
<div class="section" id="PSA_ALG_IS_RSA_PSS">
<span id="c.PSA_ALG_IS_RSA_PSS"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_RSA_PSS</span></code> (macro)</h3>
<p>Whether the specified algorithm is an RSA PSS signature algorithm.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_IS_RSA_PSS" title="PSA_ALG_IS_RSA_PSS">PSA_ALG_IS_RSA_PSS</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>An algorithm identifier: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>.</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is an RSA PSS signature algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise.</p>
<p>This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
<p class="rubric">Description</p>
<p>This macro returns <code class="docutils literal"><span class="pre">1</span></code> for algorithms constructed using either <a class="reference internal" href="#c.PSA_ALG_RSA_PSS" title="PSA_ALG_RSA_PSS"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_RSA_PSS()</span></code></a> or <a class="reference internal" href="#c.PSA_ALG_RSA_PSS_ANY_SALT" title="PSA_ALG_RSA_PSS_ANY_SALT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_RSA_PSS_ANY_SALT()</span></code></a>.</p>
</div>
<div class="section" id="PSA_ALG_IS_RSA_PSS_ANY_SALT">
<span id="c.PSA_ALG_IS_RSA_PSS_ANY_SALT"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_RSA_PSS_ANY_SALT</span></code> (macro)</h3>
<p>Whether the specified algorithm is an RSA PSS signature algorithm that permits any salt length.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_IS_RSA_PSS_ANY_SALT" title="PSA_ALG_IS_RSA_PSS_ANY_SALT">PSA_ALG_IS_RSA_PSS_ANY_SALT</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>An algorithm identifier: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>.</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is an RSA PSS signature algorithm that permits any salt length, <code class="docutils literal"><span class="pre">0</span></code> otherwise.</p>
<p>This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
<p class="rubric">Description</p>
<p>An RSA PSS signature algorithm that permits any salt length is constructed using <a class="reference internal" href="#c.PSA_ALG_RSA_PSS_ANY_SALT" title="PSA_ALG_RSA_PSS_ANY_SALT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_RSA_PSS_ANY_SALT()</span></code></a>.</p>
<p>See also <a class="reference internal" href="#c.PSA_ALG_IS_RSA_PSS" title="PSA_ALG_IS_RSA_PSS"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_IS_RSA_PSS()</span></code></a> and <a class="reference internal" href="#c.PSA_ALG_IS_RSA_PSS_STANDARD_SALT" title="PSA_ALG_IS_RSA_PSS_STANDARD_SALT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_IS_RSA_PSS_STANDARD_SALT()</span></code></a>.</p>
</div>
<div class="section" id="PSA_ALG_IS_RSA_PSS_STANDARD_SALT">
<span id="c.PSA_ALG_IS_RSA_PSS_STANDARD_SALT"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_RSA_PSS_STANDARD_SALT</span></code> (macro)</h3>
<p>Whether the specified algorithm is an RSA PSS signature algorithm that requires the standard salt length.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_IS_RSA_PSS_STANDARD_SALT" title="PSA_ALG_IS_RSA_PSS_STANDARD_SALT">PSA_ALG_IS_RSA_PSS_STANDARD_SALT</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>An algorithm identifier: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>.</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is an RSA PSS signature algorithm that requires the standard salt length, <code class="docutils literal"><span class="pre">0</span></code> otherwise.</p>
<p>This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
<p class="rubric">Description</p>
<p>An RSA PSS signature algorithm that requires the standard salt length is constructed using <a class="reference internal" href="#c.PSA_ALG_RSA_PSS" title="PSA_ALG_RSA_PSS"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_RSA_PSS()</span></code></a>.</p>
<p>See also <a class="reference internal" href="#c.PSA_ALG_IS_RSA_PSS" title="PSA_ALG_IS_RSA_PSS"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_IS_RSA_PSS()</span></code></a> and <a class="reference internal" href="#c.PSA_ALG_IS_RSA_PSS_ANY_SALT" title="PSA_ALG_IS_RSA_PSS_ANY_SALT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_IS_RSA_PSS_ANY_SALT()</span></code></a>.</p>
</div>
<div class="section" id="PSA_ALG_IS_ECDSA">
<span id="c.PSA_ALG_IS_ECDSA"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_ECDSA</span></code> (macro)</h3>
<p>Whether the specified algorithm is ECDSA.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_IS_ECDSA" title="PSA_ALG_IS_ECDSA">PSA_ALG_IS_ECDSA</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>An algorithm identifier: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>.</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is an ECDSA algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise.</p>
<p>This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
</div>
<div class="section" id="PSA_ALG_IS_DETERMINISTIC_ECDSA">
<span id="c.PSA_ALG_IS_DETERMINISTIC_ECDSA"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_DETERMINISTIC_ECDSA</span></code> (macro)</h3>
<p>Whether the specified algorithm is deterministic ECDSA.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_IS_DETERMINISTIC_ECDSA" title="PSA_ALG_IS_DETERMINISTIC_ECDSA">PSA_ALG_IS_DETERMINISTIC_ECDSA</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>An algorithm identifier: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>.</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a deterministic ECDSA algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise.</p>
<p>This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
<p class="rubric">Description</p>
<p>See also <a class="reference internal" href="#c.PSA_ALG_IS_ECDSA" title="PSA_ALG_IS_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_IS_ECDSA()</span></code></a> and <a class="reference internal" href="#c.PSA_ALG_IS_RANDOMIZED_ECDSA" title="PSA_ALG_IS_RANDOMIZED_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_IS_RANDOMIZED_ECDSA()</span></code></a>.</p>
</div>
<div class="section" id="PSA_ALG_IS_RANDOMIZED_ECDSA">
<span id="c.PSA_ALG_IS_RANDOMIZED_ECDSA"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_RANDOMIZED_ECDSA</span></code> (macro)</h3>
<p>Whether the specified algorithm is randomized ECDSA.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_IS_RANDOMIZED_ECDSA" title="PSA_ALG_IS_RANDOMIZED_ECDSA">PSA_ALG_IS_RANDOMIZED_ECDSA</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>An algorithm identifier: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>.</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a randomized ECDSA algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise.</p>
<p>This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
<p class="rubric">Description</p>
<p>See also <a class="reference internal" href="#c.PSA_ALG_IS_ECDSA" title="PSA_ALG_IS_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_IS_ECDSA()</span></code></a> and <a class="reference internal" href="#c.PSA_ALG_IS_DETERMINISTIC_ECDSA" title="PSA_ALG_IS_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_IS_DETERMINISTIC_ECDSA()</span></code></a>.</p>
</div>
<div class="section" id="PSA_ALG_IS_HASH_EDDSA">
<span id="c.PSA_ALG_IS_HASH_EDDSA"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH_EDDSA</span></code> (macro)</h3>
<p>Whether the specified algorithm is HashEdDSA.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_IS_HASH_EDDSA" title="PSA_ALG_IS_HASH_EDDSA">PSA_ALG_IS_HASH_EDDSA</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>An algorithm identifier: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>.</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a HashEdDSA algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise.</p>
<p>This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
</div>
<div class="section" id="PSA_ALG_IS_HASH_AND_SIGN">
<span id="c.PSA_ALG_IS_HASH_AND_SIGN"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH_AND_SIGN</span></code> (macro)</h3>
<p>Whether the specified algorithm is a hash-and-sign algorithm that signs exactly the hash value.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_IS_HASH_AND_SIGN" title="PSA_ALG_IS_HASH_AND_SIGN">PSA_ALG_IS_HASH_AND_SIGN</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>An algorithm identifier: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>.</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a hash-and-sign algorithm that signs exactly the hash value, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
<p>A wildcard signature algorithm policy, using <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a>, returns the same value as the signature algorithm parameterised with a valid hash algorithm.</p>
<p class="rubric">Description</p>
<p>This macro identifies algorithms that can be used with <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a> that use the exact message hash value as an input the signature operation. For example, if <a class="reference internal" href="#c.PSA_ALG_IS_HASH_AND_SIGN" title="PSA_ALG_IS_HASH_AND_SIGN"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH_AND_SIGN</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true, the following call sequence is equivalent to <a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message"><code class="docutils literal"><span class="pre">psa_sign_message</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">key</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">msg</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">msg_len</span></code><code class="docutils literal"><span class="pre">,</span> <span class="pre">...)</span></code>:</p>
<pre class="literal-block">
<a class="reference internal" href="hashes.html#c.psa_hash_operation_t" title="psa_hash_operation_t">psa_hash_operation_t</a> op = {0};
uint8_t hash[<a class="reference internal" href="hashes.html#c.PSA_HASH_MAX_SIZE" title="PSA_HASH_MAX_SIZE">PSA_HASH_MAX_SIZE</a>];
size_t hash_len;
<a class="reference internal" href="hashes.html#c.psa_hash_setup" title="psa_hash_setup">psa_hash_setup</a>(&amp;op, <a class="reference internal" href="algorithms.html#c.PSA_ALG_GET_HASH" title="PSA_ALG_GET_HASH">PSA_ALG_GET_HASH</a>(alg));
<a class="reference internal" href="hashes.html#c.psa_hash_update" title="psa_hash_update">psa_hash_update</a>(&amp;op, msg, msg_len);
<a class="reference internal" href="hashes.html#c.psa_hash_finish" title="psa_hash_finish">psa_hash_finish</a>(&amp;op, hash, sizeof(hash), &amp;hash_len);
<a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash">psa_sign_hash</a>(key, alg, hash, hash_len, ...);
</pre>
<p>This excludes hash-and-sign algorithms that require a encoded or modified hash for the signature step in the algorithm, such as <a class="reference internal" href="#c.PSA_ALG_RSA_PKCS1V15_SIGN_RAW" title="PSA_ALG_RSA_PKCS1V15_SIGN_RAW"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_RSA_PKCS1V15_SIGN_RAW</span></code></a>. For such algorithms, <a class="reference internal" href="#c.PSA_ALG_IS_SIGN_HASH" title="PSA_ALG_IS_SIGN_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_IS_SIGN_HASH()</span></code></a> is true but <a class="reference internal" href="#c.PSA_ALG_IS_HASH_AND_SIGN" title="PSA_ALG_IS_HASH_AND_SIGN"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_IS_HASH_AND_SIGN()</span></code></a> is false.</p>
</div>
<div class="section" id="PSA_ALG_ANY_HASH">
<span id="c.PSA_ALG_ANY_HASH"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code> (macro)</h3>
<p>When setting a hash-and-sign algorithm in a key policy, permit any hash algorithm.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH">PSA_ALG_ANY_HASH</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x020000ff)
</pre>
<p>This value can be used to form the permitted algorithm attribute of a key policy for a signature algorithm that is parametrized by a hash. A key with this policy can then be used to perform operations using the same signature algorithm parametrized with any supported hash.
A signature algorithm created using this macro is a wildcard algorithm, and <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_WILDCARD" title="PSA_ALG_IS_WILDCARD"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_IS_WILDCARD()</span></code></a> will return true.</p>
<p>This value must not be used to build other algorithms that are parametrized over a hash. For any valid use of this macro to build an algorithm <code class="docutils literal"><span class="pre">alg</span></code>, <a class="reference internal" href="#c.PSA_ALG_IS_HASH_AND_SIGN" title="PSA_ALG_IS_HASH_AND_SIGN"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH_AND_SIGN</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</p>
<p>This value must not be used to build an algorithm specification to perform an operation. It is only valid for setting the permitted algorithm in a key policy.</p>
<p class="rubric">Usage</p>
<p>For example, suppose that <code class="docutils literal"><span class="pre">PSA_xxx_SIGNATURE</span></code> is one of the following macros:</p>
<ul class="simple">
<li><a class="reference internal" href="#c.PSA_ALG_RSA_PKCS1V15_SIGN" title="PSA_ALG_RSA_PKCS1V15_SIGN"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_RSA_PKCS1V15_SIGN</span></code></a></li>
<li><a class="reference internal" href="#c.PSA_ALG_RSA_PSS" title="PSA_ALG_RSA_PSS"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_RSA_PSS</span></code></a></li>
<li><a class="reference internal" href="#c.PSA_ALG_RSA_PSS_ANY_SALT" title="PSA_ALG_RSA_PSS_ANY_SALT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_RSA_PSS_ANY_SALT</span></code></a></li>
<li><a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a></li>
<li><a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a></li>
</ul>
<p>The following sequence of operations shows how <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a> can be used in a key policy:</p>
<ol class="arabic">
<li><p class="first">Set the key usage flags using <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a>, for example:</p>
<pre class="literal-block">
<a class="reference internal" href="../keys/policy.html#c.psa_set_key_usage_flags" title="psa_set_key_usage_flags">psa_set_key_usage_flags</a>(&amp;attributes, <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_SIGN_MESSAGE" title="PSA_KEY_USAGE_SIGN_MESSAGE">PSA_KEY_USAGE_SIGN_MESSAGE</a>); // or VERIFY_MESSAGE
<a class="reference internal" href="../keys/policy.html#c.psa_set_key_algorithm" title="psa_set_key_algorithm">psa_set_key_algorithm</a>(&amp;attributes, PSA_xxx_SIGNATURE(<a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH">PSA_ALG_ANY_HASH</a>));
</pre>
</li>
<li><p class="first">Import or generate key material.</p>
</li>
<li><p class="first">Call <a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_message()</span></code></a> or <a class="reference internal" href="#c.psa_verify_message" title="psa_verify_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_message()</span></code></a>, passing an algorithm built from <code class="docutils literal"><span class="pre">PSA_xxx_SIGNATURE</span></code> and a specific hash. Each call to sign or verify a message can use a different hash algorithm.</p>
<pre class="literal-block">
<a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message">psa_sign_message</a>(key, PSA_xxx_SIGNATURE(<a class="reference internal" href="hashes.html#c.PSA_ALG_SHA_256" title="PSA_ALG_SHA_256">PSA_ALG_SHA_256</a>), ...);
<a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message">psa_sign_message</a>(key, PSA_xxx_SIGNATURE(<a class="reference internal" href="hashes.html#c.PSA_ALG_SHA_512" title="PSA_ALG_SHA_512">PSA_ALG_SHA_512</a>), ...);
<a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message">psa_sign_message</a>(key, PSA_xxx_SIGNATURE(<a class="reference internal" href="hashes.html#c.PSA_ALG_SHA3_256" title="PSA_ALG_SHA3_256">PSA_ALG_SHA3_256</a>), ...);
</pre>
</li>
</ol>
</div>
<div class="section" id="PSA_SIGN_OUTPUT_SIZE">
<span id="c.PSA_SIGN_OUTPUT_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_SIGN_OUTPUT_SIZE</span></code> (macro)</h3>
<p>Sufficient signature buffer size for <a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_message()</span></code></a> and <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a>.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_SIGN_OUTPUT_SIZE" title="PSA_SIGN_OUTPUT_SIZE">PSA_SIGN_OUTPUT_SIZE</a>(key_type, key_bits, alg) \
    <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">key_type</span></code></dt>
<dd>An asymmetric key type. This can be a key pair type or a public key type.</dd>
<dt> <code class="docutils literal"><span class="pre">key_bits</span></code></dt>
<dd>The size of the key in bits.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>The signature algorithm.</dd>
</dl>
<p class="rubric">Returns</p>
<p>A sufficient signature buffer size for the specified asymmetric signature algorithm and key parameters. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or a correct size for an asymmetric signature algorithm and key parameters that it recognizes, but does not support. If the parameters are not valid, the return value is unspecified.</p>
<p class="rubric">Description</p>
<p>If the size of the signature buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_message()</span></code></a> and <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a> will not fail due to an insufficient buffer size. The actual size of the output might be smaller in any given call.</p>
<p>See also <a class="reference internal" href="#c.PSA_SIGNATURE_MAX_SIZE" title="PSA_SIGNATURE_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SIGNATURE_MAX_SIZE</span></code></a>.</p>
</div>
<div class="section" id="PSA_SIGNATURE_MAX_SIZE">
<span id="c.PSA_SIGNATURE_MAX_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_SIGNATURE_MAX_SIZE</span></code> (macro)</h3>
<p>A sufficient signature buffer size for <a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_message()</span></code></a> and <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a>, for any of the supported key types and asymmetric signature algorithms.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_SIGNATURE_MAX_SIZE" title="PSA_SIGNATURE_MAX_SIZE">PSA_SIGNATURE_MAX_SIZE</a> <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
</pre>
<p>If the size of the signature buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_message()</span></code></a> and <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a> will not fail due to an insufficient buffer size.</p>
<p>See also <a class="reference internal" href="#c.PSA_SIGN_OUTPUT_SIZE" title="PSA_SIGN_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SIGN_OUTPUT_SIZE()</span></code></a>.</p>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
IHI 0086<br/>
Non-confidential<br/>
Version 1.1.0
<span style="color: red; font-weight: bold;"></span>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../about.html">About this document</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="../keys/index.html">9. Key management reference</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">10. Cryptographic operation reference</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="algorithms.html">10.1. Algorithms</a></li>
<li class="toctree-l2"><a class="reference internal" href="hashes.html">10.2. Message digests (Hashes)</a></li>
<li class="toctree-l2"><a class="reference internal" href="macs.html">10.3. Message authentication codes (MAC)</a></li>
<li class="toctree-l2"><a class="reference internal" href="ciphers.html">10.4. Unauthenticated ciphers</a></li>
<li class="toctree-l2"><a class="reference internal" href="aead.html">10.5. Authenticated encryption with associated data (AEAD)</a></li>
<li class="toctree-l2"><a class="reference internal" href="kdf.html">10.6. Key derivation</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">10.7. Asymmetric signature</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#asymmetric-signature-algorithms">10.7.1. Asymmetric signature algorithms</a></li>
<li class="toctree-l3"><a class="reference internal" href="#asymmetric-signature-functions">10.7.2. Asymmetric signature functions</a></li>
<li class="toctree-l3"><a class="reference internal" href="#support-macros">10.7.3. Support macros</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="pke.html">10.8. Asymmetric encryption</a></li>
<li class="toctree-l2"><a class="reference internal" href="ka.html">10.9. Key agreement</a></li>
<li class="toctree-l2"><a class="reference internal" href="rng.html">10.10. Other cryptographic services</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../appendix/encodings.html">Algorithm and key type encoding</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../appendix/sra.html">Security Risk Assessment</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
</ul>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <form class="search" action="../../search.html" method="get">
      <div><input type="text" name="q" /></div>
      <div><input type="submit" value="Go" /></div>
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="footer">
      &copy; 2018-2022, Arm Limited or its affiliates. All rights reserved.
      
      |
      Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
      
    </div>

    

    
  </body>
</html>